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In this document I'll try to give a complete description of the TMS9918A in
software behaviour and display output. I only know the VDP in the MSX system,
in other systems it may have features not described here.

You can always find the latest version of this document at:

	http://www.msxnet.org/tech/

Distribution of this document is unlimited. Any comments are very welcome.
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1) Overview
-----------

The VDP is quite simple with 16kB of video memory (or 4kB, but I don't know 
anything about this setup). The display always has a resolution of 256 pixels 
horizontal and 192 pixels vertical. Around this area, there is the border 
colour (back drop) which can be set in the registers. There also is a sprite 
subsystem, with maximum of 4 sprites on a row.

There is a PAL version of the chip, and a NTSC version. As far as I know the 
only difference to the system is the interrupt speed: 50Hz for PAL and 60Hz for
NTSC.

The TMS9918A was used in quite a few systems: MSX1, Coleco, TI99/4A and 
probably more. I only know it in the MSX1 system.


1.1) Colours

There are 16 colours. These are static; they can't be changed. Colour 0 is
transparent. I don't know what the exact colours are in colour intensity.
However, the V9938 (MSX2 VDP chip, compatible with the TMS9918A) uses the 
following colours, from 0 to 7:

			Green	Red	Blue
 1. Black		0	0	0
 2. Medium Green	6	1	1
 3. Light Green		7	3	3
 4. Dark Blue		1	1	7
 5. Light Blue		3	2	7
 6. Dark Red		1	5	1
 7. Cyan		6	2	7
 8. Medium Red		1	7	1
 9. Light Red		3	7	3
10. Dark Yellow		6	6	1
11. Light Yellow	6	6	4
12. Dark Green		4	1	1
13. Magenta		2	6	5
14. Grey		5	5	5
15. White		7	7	7

You can view these colours at:

	http://www.msxnet.org/tech/colours.png


1.2) Registers

The VDP has 8 control registers (0-7) and one status register. 

Control Registers:

Reg/Bit	7	6	5	4	3	2	1	0
0	-	-	-	-	-	-	M2	B/W
1	4/16K	BL	GINT	M1	M3	-	SI	MAG
2	-	-	-	-	PN13	PN12	PN11	PN10
3	CT13	CT12	CT11	CT10	CT9	CT8	CT7	CT6
4	-	-	-	-	-	PG13	PG12	PG11
5	-	SA13	SA12	SA11	SA10	SA9	SA8	SA7
6	-	-	-	-	-	SG13	SG12	SG11
7	TC3	TC2	TC1	TC0	BD3	BD2	BD1	BD0

Status Register:

	7	6	5	4	3	2	1	0
	INT	5S	C	FS4	FS3	FS2	FS1	FS0

The function of the bits is as follows:

M1,M2,M3	Select screen mode
B/W		Only black & white output (??)
4/16K		Selects 16kB RAM if set. No effect in MSX1 system (??)
BL		Blank screen if reset; just backdrop. Sprite system inactive
SI		16x16 sprites if set; 8x8 if reset
MAG		Sprites enlarged if set (sprite pixels are 2x2)
GINT		Generate INTs if set
PN*		Address for pattern name table
CT*		Address for colour table (special meaning in M2)
PG*		Address for pattern generator table (special meaning in M2)
SA*		Address for sprite attribute table
SG*		Address for sprite generator table
TC*		Text colour (foreground)
BD*		Back drop (background). Sets the colour of the border around
		the drawable area. If it is 0, it is black (like colour 1).
FS*		Fifth sprite (first sprite that's not displayed). Only valid
		if 5S is set.
C		Sprite collision detected
5S		Fifth sprite (not displayed) detected. Value in FS* is valid.
INT		Set at each screen update, used for interrupts.

The exact meaning of all these bits should become clear in the remainder of 
this document.

The bits marked with `-' are "don't care": set or reset, doesn't make any
difference. However, to maintain downwards compatiblility, you should 
reset these bits.

2) I/O with the VDP
-------------------

The VDP has two I/O ports (#0 and #1) which can be read or written. In the MSX
system, they are mapped to port 98h and 99h. The VDP also has an INT output,
which can be used by the CPU to detect screen updates (or vertical blank).


2.1) Memory access

The 16kB memory can't be accessed directly; only through the I/O ports. To the
contrary to what many (official!) docs say, there is only one read/write 
address where the VDP reads or writes in the 16kB memory. There also is a 
read-ahead buffer, which stores one byte. Memory is "read ahead", so when a
read is requested, it can give the value immediately.

This memory address (the r/w address) can be set by writing two bytes to port 
#1. Despite the fact there is only one address, a distinction is made between 
setting it for reading or writing (this because of the read-ahead buffer).

The two bytes are formatted as follows:

		7	6	5	4	3	2	1	0
Byte #0		A7	A6	A5	A4	A3	A2	A1	A0
Byte #1		0	R/W	A13	A12	A11	A10	A9	A8

A13-A0 make up the address. R/W specifies whether you want to read or write
from that address. It should be 0 for reading, 1 for writing.

What happens internally in the VDP is interesting. This depends on what you
set the R/W bit to:

Write (1):	Simply set the r/w address to the A* value specified.
Read (0):	Read the contents of the A* address from the VRAM and put it
		in the read-ahead buffer. Set the r/w address to A* + 1.

Now that the r/w address is set, we can start reading from or writing to it. 
After each access it is increased. By reading port #0 we can read from the 
address, by writing to it we write to the address. What happens internally is:

Read:	Return value in read-ahead buffer. Read next value from the r/w 
	address, put it in the read-ahead buffer. Increase the r/w address.
Write:	Write back the value to the r/w address, then increase the r/w address.
	Interestingly, the value written is also stored in the read-ahead 
	buffer.

After 3fffh (16kB limit) the r/w address wraps to zero.


2.2) Register access

The status register can only be read; the control registers can't be read so 
they can only can be written.

By reading port #1, you get the value of the status register. After reading
it, bit 7 (INT bit) and bit 5 (C bit) are reset.

By writing to port #1, a control register is set. Two bytes must be written
to port #1:

		7	6	5	4	3	2	1	0
Byte #0		V7	V6	V5	V4	V3	V2	V1	V0
Byte #1		1	?	?	?	?	R2	R1	R0

The V* bits make up the value written to the register, which is specified
with the R* bits. Bits 6-3 of the second byte are "don't care": it doesn't
matter what value you set them. Officially, they must be 0. It is best to
set them to 0. The downwards TMS9918A compatible V9938 and V9958 have more 
registers and so these bits do have meaning. So, for compatibility, set them 
to 0. Bit 7 must be set, to indicate you want to write to a register; otherwise
you're changing the r/w address.


2.3) I/O Ports quirks

As you've probably noticed, writes to port #1 must always go in pairs of two
bytes. Suppose you would write one byte to port #1, and let normal programming
continue .. you'd assume that the byte order of any port #1 write is wrong and 
strange things happen. But that isn't true.

What happens internally is this. After writing the first byte to port #1, a 
flag is set to indicate that the next byte written to port #1 is the second of 
the pair and completes the register write or r/w address set. This flag is 
reset after that.

But this flag is also reset whenever you read port #1, or read or write port
#0. This probably done to prevent an accidental single write to port #1 mess up
the whole programming (which without this setup, would require a hard reset or 
another write to port #1 to return to normal operation).

So, in between writing two bytes to port #1, never access any other port of the
VDP. This is why interrupts must be disabled during writing to port #1: the 
interrupt service routine most likely accesses the VDP (status register read 
for example) and that will mess it up.


2.4) Interrupts

The VDP can generate interrupts for the CPU. It works as follows: at the end
of the last line of the screen (after vertical line 192, last of the drawable 
screen; at the begining of the bottom part of the backdrop) bit 7 of status 
register is set. 

If bit 7 of the status register is set (INT), and bit 5 of control register #1
is set (GINT), the INT output line is low (requesting an interrupt), otherwise
it is high (not requesting an interrupt).

So if bit 5 of control register #1 is reset, interrupts are never requested.

After the status register is read, bit 7 is reset. The INT line goes high
again, so it isn't requesting an interrupt anymore. That's why this register
must always be read in an interrupt routine: otherwise the INT is remains low
and the interrupt service routine is called again and again.

Another interesting fact is this: if bit 5 of control register #1 is reset,
and you set it, and bit 7 of the status register was set, the INT line goes
low immediately and an interrupt is requested. This is important for emulators
too: if this isn't emulated properly, the MSX game Track & Field 1 and 2 slows
down considerbly.


3) Screen modes
---------------

There are 4 official screen modes but 3 mode bits (8 possibilities). The
modes define how the screen is built up. In some modes, the sprite subsystem
is active which is described in section 4).

All screen modes are character based.

Screen mode x simply means the respective Mx bits are set. Mode 0 indicates
none of the M* bits are set.


3.1) Mode 0 

This screen mode is known as SCREEN 1 in MSX BASIC, and GRAPHIC 1 in the
V9938 Technical Data Book.

Like most screen modes, it has width 32 characters and 24 characters vertical.
The sprite subsystem is active.

Since the size is 32 x 24, the Pattern Name Table (PN) has 32 x 24 = 768 
elements, which are bytes refering to the Pattern Generator Table (PG) and 
Colour Table (CT). 

The first character is the top-left one, the second the one to the right of
it. Character no. 32 the first character of the second row.

Each character is 8 x 8. The character number refers to an character pattern in
the PG, which has 256 characters patterns. Each pattern is 8 bytes, so the
entire PG is 256 x 8 = 2048 bytes. Each byte is a pixel line of the character 
(top first). If a bit is set, the foreground colour in the CT is shown, 
otherwise the background colour in the CT.

The CT sets the colour of the character. Each byte in the CT sets the colour 
of 8 complete characters, so the CT is 32 bytes. The high four bits set the
foreground colour, the low the background colour. If either of these is 0,
it is transparent and the colour of the backdrop (BD) is used. To calculate
the element in the CT, divide the character number in PN by 8.

The TC in control register #7 is not used in this mode.


3.2) Mode 1

This mode is known as SCREEN 0 in MSX BASIC, and as TEXT 1 in the V9938 
Technical Data Book.

In this mode, the screen has width 40 characters and 24 characters vertical. 
Only two colours are used, TC and BD from control register #7. Since the 
characters are 6 pixels wide, the width is 40 x 6 = 240. There is a 8 pixels
border at the left and right side of the screen (with the colour of the back 
drop). The sprite subsystem is inactive.

Since the size is 40 x 24, the Pattern Name Table (PN) has 40 x 24 = 960 
elements, which are bytes refering to the Pattern Generator Table (PG). The
Colour Table (CT) is not used.

The first character is the top-left one, the second the one to the right of
it. Character no. 40 the first character of the second row.

Each character is 6 x 8 pixels. The character number refers to a character 
pattern in the PG, which has 256 characters patterns. Each pattern is 8 bytes, 
so the entire PG is 256 x 8 = 2048 bytes. Each byte is a pixel line of the 
character (top first). If a bit is set, the TC in control register #7 is shown,
otherwise BD in the same register. The two highest bits of each byte in the PG
are ignored.


3.3) Mode 2

This mode is known as SCREEN 2 in MSX BASIC, and as GRAPHIC 2 in the V9938 
Data Book. It is the most complex and has the most possibilities of all the 
modes of the TMS9918A.

Like most screen modes, it has width 32 characters and 24 characters vertical.
The sprite subsystem is active.

Since the size is 32 x 24, the Pattern Name Table (PN) has 32 x 24 = 768 
elements, which are bytes refering to the Pattern Generator Table (PG) and 
Colour Table (CT). 

The first character is the top-left one, the second the one to the right of
it. Character no. 32 the first character of the second row. There are three
colour and three pattern tables. The character number is as follows:

The first 8 rows: byte from PN + 000h
The middle 8 rows: byte from PN + 100h
The bottom 8 rows: byte from PN + 200h

Each character is 8 x 8. The character number refers to an character pattern in
the PG, which has 768 characters patterns (three seperate tables). For the first
8 rows of the screen, the first 256 entries are used. For the second 8 rows,
the second 256 patterns, and for the last 8 rows the third 256 patterns 
(depending on the value of control register #4, see below). So the entire PG is
3 x 256 x 8 = 6144 bytes. Each byte is a pixel line of the character (top 
first). If a bit is set, the foreground colour in the CT is used, otherwise 
the background colour in the CT.

Control register #4 which sets the PG address of the PG has a different 
function in mode 2. Only bit 2, PG13, sets the address of the PG (so it's either
address 0 or 2000h). Bits 0 and 1 are an AND mask over the character number. 
The character number is 0 - 767 (2FFh) and these two bits are ANDed over the 
two highest bits of this value (2FFh is 10 bits, so over bit 8 and 9). So in 
effect, if bit 0 of control register #4 is set, the second array of 256 
patterns in the PG is used for the middle 8 rows of characters, otherwise the 
first 256 patterns. If bit 1 is set, the third array of patterns is used in 
the PG, otherwise the first.

The relation PN -> CT is the same as PN -> GT. Each byte in the CT sets the
colour of one pixel line of a character.  The high four bits set the foreground 
colour, the low the background colour. If either of these is 0, it is 
transparent and the colour of the backdrop (BD) is used. 

Also control register #3 has a different meaning. Only bit 7 (CT13) sets the CT
address. Somewhat like control register #4 for the PG, bits 6 - 0 are an AND
mask over the top 7 bits of the character number.

The TC in control register #7 is not used in this mode.


3.4) Mode 3

This mode is known as SCREEN 3 in MSX-BASIC, and as MULTICOLOR in the V9938
Technical Data Book. In this mode, each `unit' on the screen is 4 x 4 pixels. 
In these units all the pixels have the same colour. Unlike all the other modes
there is no colour spill (each pixel can have any colour). The sprite subsystem 
is active.

The characters are 8 x 8 pixels. There are 32 x 24 characters on the screen,
so the pattern name table (PN) has 768 elements (bytes) which refer to a 
pattern in the pattern generator table (PG). Only two bytes of the 8 bytes in
the pattern are used. Which two bytes depends on the vertical row (0 - 23).
The address in the PG can be calculated as follows:

	PG + (byte in PN) x 8 + (row AND 3) x 2

Each character is 4 units. Each byte sets the color of two blocks of 4 x 4 
pixels. The lower four bits set the colour of the left block, the highest four 
bits set the colour of the right block. If either is 0, the block is transparent
and the backdrop (BD) is visible. 

The TC in control register #7 is not used in this mode, neither is the colour
table (CT).


3.5) Undocumented Mode 1 + 2

This mode is very much like Mode 1; the difference is that there can be three
different pattern tables, and control register #4 has a different meaning.

The pattern table now has 3 x 256 patterns; the screen is divided in three
parts (the top 8 character rows, the middle 8, the bottom 8). Each part can
use a different part of the pattern generator table (the first 256, the second 
256, the last 256). The top part always uses the first 256 patterns in the PG.

Control register #4:
 bit 7 - 3 : ignored
 bit 2     : PG13; if set, PG = 2000h otherwise 0
 bit 1 	   : if set, the last 8 rows use the 3rd pattern table otherwise 1st.
 bit 0     : if set, the middle 8 rows use the 2nd pattern table otherwise 1st.

This undocumented mode is not available in the V9938 as far as I know.


3.6) Undocumented Mode 2 + 3

This mode is very much like Mode 3; it differs in the same way that 
undocumented mode 1 + 2 differs from mode 1. See section above for details.


3.7) Other (Mode 1+3 and Mode 1+2+3)

There are two undocumented modes left: 1+3 and 1+2+3. Something weird happens
in both modes: no longer do the tables have any influence on how the screen looks 
like. The screen simply shows 40 vertical lines of text colour (TC). By the 
looks of it, it's 4 pixels TC, 2 pixels BD. Like in mode 1, there is a 8 pixel
border with colour backdrop (BD) at the left and right of the screen.

The sprite subsystem is inactive.


4) Sprite system
----------------

In all modes except when M1 is set or BL is reset, the sprite subsystem is 
active. Sprites can be either 8 x 8 pixels, or 16 x 16; also these pixels can 
be enlarged (twice the size; "zoomed").


4.1) Sprite attribute table

32 different sprites can be display at the same time on the same screen, with
the exception that no more than 4 four sprites can be displayed on one 
horizontal pixel line. The location and colour of the sprites is specified in 
the sprite attribute table (SA). For each of the 32 sprites, there are four 
bytes.

SA ->	0	Y sprite 0
	1	X sprite 0
	2	sprite pattern 0
	3	colour sprite 0 + EC
	4	Y sprite 1
	5	X sprite 1
	6	sprite pattern 1
	7	colour sprite 1 + EC
	.
	.

The values have special meanings. If the Y coordinate is 0, it's displayed on
the second pixel line from the top. With value 255 it's exactly on the the top
line, and with coordinate 254 the top line isn't visible any more, with 253 to
two top lines aren't visible any more, etc.

If Y is 208, that sprite and all following sprites in the table are not 
displayed.

The X coordinate is simply, as you would expect, the X coordinate from 0 to 
255. If bit 7 of the ``colour sprite'' is set (Early Clock -- EC), the sprite
is moved 32 pixels to the left; in this way it's possible to partially display
the sprite at the left side.

The lower 4 bits of ``colour sprite'' define the colour. Bit 7 is the EC.
Bits 6 - 4 should be zero officially, but they are ignored. If the colour is 
0, the sprite is transparent (not visible).


4.2) Sprite generator & sizes

These options are in the control register #1. If bit 0 (MAG) is set, the 
sprites are enlarged. If bit 1 (SI) is set, the sprites are 16 x 16 in size,
otherwise 8 x 8.

The sprite pattern defines which pattern to use. In the case of 8 x 8 sprites,
there are 8 bytes for the sprite pattern, and there are 256 patterns in the
sprite generator table (SG). So simply multiply the sprite pattern by 8 to 
get the address in the SG. Each of these bytes set the colour of the pixels
of the sprite. If a bit is set, the pixel has the colour of the ``colour
sprite'' -- unless it is 0, in which case it is transparent.

In the case of 16 x 16, it is slightly more complex. The SG is still 256 x 8
bytes, and each pattern is 32 bytes now. To calculate the address in the
SG: ((pattern number) AND 252) x 8. The first 16 bytes set the colour of the
left 8 pixels of the sprite, the next 16 bytes set the colour of the right
16 pixels of the sprite. If it is 0, it is transparent.

If bit 0 of control register 1 (MAG) is set, the sprites are enlarged. The
starting coordinates are the same, but every pixel of the sprite is 2 x 2 
real pixels. 


4.3) Illegal sprites & sprite collision

On each horizontal pixel line, only 4 sprites are allowed. Any more than that 
are not displayed. These sprites that aren't displayed are known as ``illegal
sprites''. The first sprite illegal sprite that is detected is put in the
status register. Bit 6 (5S) is set, to show an illegal sprite is detected. The
sprite number (SA element number) is stored in the FS* bits. Note that even 
transparent (colour 0) sprites count for illegal sprites, and sprites that 
aren't displayed because they're of the left or right side of the screen.

If no illegal sprite was found, 5S won't be set and FS* contains the highest
sprite number in the SA, either the last (31) or the first with Y coordinate
208 (if it exists). Note that isn't fully checked (but probably not really
important).

Remember the screen is built line by line from top to bottom; the first illegal
sprite is on the highest pixel line with an illegal sprite.

If anywhere on the screen two or more sprites overlap, the C bit of the status
register is set. The colour of the sprite is not important (can even be 0), the 
pattern is. If a sprite line is not displayed because it is illegal, it does 
not count for sprite collision. The C bit of the status register is reset
after the register is read.


5) Hardware
-----------

5.1) Pin outs

		    TMS9918A

		+--------------+
	   _RAS | 1	    40 | XLAT2 
	   _CAS | 2	    39 | XLAT1
	    AD7 | 3	    38 | CPUCLK
	    AD6 | 4	    37 | GROMCLK
	    AD5 | 5	    36 | COMVID
	    AD4 | 6	    35 | EXTVDP
	    AD3 | 7	    34 | _RESET / SYNC
	    AD2	| 8	    33 | Vcc
	    AD1 | 9	    32 | RD0
	    AD0 | 10	    31 | RD1
	   R/_W | 11	    30 | RD2
	    Vss | 12	    29 | RD3
	   MODE | 13	    28 | RD4
	   _CSW | 14	    27 | RD5
	   _CSR | 15	    26 | RD6
	   _INT | 16	    25 | RD7
	    CD7 | 17	    24 | CD0
	    CD6 | 18	    23 | CD1
	    CD5 | 19	    22 | CD2
	    CD4	| 20	    21 | CD3
		+--------------+


		    TMS9928A

		+--------------+
	   _RAS | 1	    40 | XLAT2 
	   _CAS | 2	    39 | XLAT1
	    AD7 | 3	    38 | R-Y
	    AD6 | 4	    37 | GROMCLK
	    AD5 | 5	    36 | Y
	    AD4 | 6	    35 | B-Y
	    AD3 | 7	    34 | _RESET / SYNC
	    AD2	| 8	    33 | Vcc
	    AD1 | 9	    32 | RD0
	    AD0 | 10	    31 | RD1
	   R/_W | 11	    30 | RD2
	    Vss | 12	    29 | RD3
	   MODE | 13	    28 | RD4
	   _CSW | 14	    27 | RD5
	   _CSR | 15	    26 | RD6
	   _INT | 16	    25 | RD7
	    CD7 | 17	    24 | CD0
	    CD6 | 18	    23 | CD1
	    CD5 | 19	    22 | CD2
	    CD4	| 20	    21 | CD3
		+--------------+



6) References
-------------

Unfortunately, I don't have any really good TMS9918A documentation, but using
information from various sources I was able to put this together. 

MSX Handboek voor gevorderden
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V9938 MSX-Video Technical Data Book
	The be-all, end-all guide to the MSX2 VDP; some things are true for the
	TMS9918A VDP too.

http://www.msxnet.org/tech/tmsposting.txt
	A posting by Paul Urbanus (urb@onramp.net) in comp.emulators.misc.
	Very interesting stuff about timings and the one r/w address.

http://home.swipnet.se/~w-16418/tech_vdp.htm
	This is an expanded version of my original tms9918a document. It's more 
	complete than my old version, but this document should be better. :-)

http://mess.emuverse.com/
	The MESS emulator, includes a TMS9928A emulator written by me, all 
	undocumented features described here are emulated.

